Summary

Re-implements custom container user permissions via PUID and PGID environment variables, fixing the issues that caused the original PR #9633 to be reverted (#9690).

Fixes #9657

What changed

Dockerfile

• Added su-exec package for privilege dropping
• Added chmod g=u /run/pgadmin — was missing, required for OpenShift random UIDs to write to this directory

entrypoint.sh

• Added PUID/PGID environment variable support with input validation (must be numeric, PUID=0 rejected)
• When running as root (--user root): reassigns pgadmin user to target UID/GID, fixes ownership of runtime directories before any initialization, runs all commands via su-exec
• When not root (default or OpenShift): unchanged behavior
• Fixed pgpass file operations: quoted paths, added chown when running as root
• Wrapped all Python invocations in $SU_EXEC to prevent root-owned file creation

Why the original PR was reverted

The original implementation (#9633) had three critical issues:

1. Removed USER 5050 from Dockerfile — container ran as root by default (security regression)
2. DB initialization ran as root — run_pgadmin.py and load-servers created root-owned files in /var/lib/pgadmin. The chown -R happened after init, so if anything failed between init and chown, the volume was left root-owned and inaccessible
3. OpenShift incompatibility — hardcoded UID 5050, required root for usermod/chown, rejected by OpenShift's restricted-v2 SCC

How this fix addresses each issue

1. USER 5050 is preserved — default behavior is completely unchanged
2. Privileges are dropped before initialization, not after — all init scripts (run_pgadmin.py, load-servers, set-prefs) run as the target user via su-exec, so files are created with correct ownership from the start. No post-hoc chown fixup needed for init files.
3. OpenShift works without any special configuration — see details below

Three supported modes

OpenShift compatibility details

On OpenShift with restricted-v2 SCC:

• The SCC overrides USER 5050 with a random UID from the namespace range (e.g., 1001320000-1001329999)
• The container does not run as root — id -u returns the random UID, so the else branch is taken
• The random UID is in GID 0 (root group). All runtime directories have chmod g=u in the Dockerfile, making them group-writable by GID 0
• The passwd fixup adds an /etc/passwd entry for the random UID (needed for whoami, Python's os.getlogin(), etc.)
• No chown is needed — file access works through group permissions
• Do not set runAsUser: 5050 or fsGroup: 5050 in the pod spec — let the SCC assign the UID

The reported error .spec.securityContext.fsGroup: Invalid value: []int64{5050}: 5050 is not an allowed group occurs when the pod spec explicitly sets fsGroup: 5050, which the SCC rejects. The fix is to remove those fields from the pod spec.

Usage examples

# Default (unchanged behavior)
docker run -d -p 80:80 \
  -e PGADMIN_DEFAULT_EMAIL=admin@example.com \
  -e PGADMIN_DEFAULT_PASSWORD=secret \
  pgadmin4

# Custom UID/GID (match host user)
docker run -d -p 80:80 --user root \
  -e PUID=1000 -e PGID=1000 \
  -e PGADMIN_DEFAULT_EMAIL=admin@example.com \
  -e PGADMIN_DEFAULT_PASSWORD=secret \
  -v pgadmin-data:/var/lib/pgadmin \
  pgadmin4

# OpenShift (no special flags needed)
# Just deploy — the SCC handles UID assignment

Test plan

• Default mode (USER 5050): container starts, pgAdmin accessible, can connect to PostgreSQL server
• OpenShift simulation (--user 1001320000:0): container starts, pgAdmin accessible
• Custom UID mode (--user root -e PUID=1000 -e PGID=1000): container starts, files owned by 1000:1000
• Invalid PUID (non-numeric): container exits with clear error
• PUID=0: container exits with clear error
• Volume persistence: restart with same PUID/PGID, data preserved
• Volume ownership change: restart with different PUID/PGID, chown corrects ownership

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Fixed permission and ownership handling for pgAdmin directories and configuration files in container environments.
  • Improved validation and error handling for critical startup files.

• Chores

  • Enhanced container runtime configuration for improved security practices.
  • Added support for custom user and group ID specification in container deployments.